home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / graphic / xv_pc16a.zip / XVIEW_PC.TXT < prev    next >
Text File  |  1994-04-26  |  36KB  |  706 lines
  1. XView-PC: Graphical User Interface for Turbo C and Turbo Pascal
  2. ---------------------------------------------------------------
  3.  
  4. By:
  5. Antonio Carlos Moreirao de Queiroz
  6. Department of Electronic Engineering and COPPE
  7. Federal University of Rio de Janeiro, Brazil
  8. e-mail: acmq@coe.ufrj.br
  9.  
  10. INTRODUCTION
  11. ------------
  12.  
  13.   The XView-PC graphical user interface attempts to be similar to the XView
  14. toolkit used in Sun workstations, in a simplified from.
  15.   It can be used in Pascal, C, or C++ versions. The interface is the same in
  16. any of the versions, with minor differences in the Pascal version.
  17.   The interface was initially developed as an intermediate step in porting
  18. programs from the PC to Sun workstations, by implementing a subset of the
  19. Sun XView toolkit in the PC. The work was not completed because it soon
  20. become clear that a total translation would be unnecessarily complex. Even
  21. so, the working of the two interfaces was kept similar when reasonable.
  22.   What can be done with the interface in its present form can be repeated
  23. with the Sun XView without significant structural changes, although with
  24. differences due to the various simplifications made. The porting of an
  25. application to Windows is also not complex.
  26.   The interface code is of simple use and adds only about 25 k to the
  27. executable program doing all the user interface functions. It works with any
  28. PC compatible computer, in any graphics mode supported by the BGI drivers and
  29. installed mouse driver. If a mouse is not installed, a mouse emulator using
  30. the keyboard is automatically used.
  31.   To simplify the interface code generation, an interface editor program,
  32. X_MAKE.EXE, is included. It allows the edition of a complete user
  33. interface, and the automatic generation of an skeleton program in Pascal or
  34. C, that is a fully functional program that the user can edit and complete.
  35.  
  36. TYPICAL PROGRAM STRUCTURE
  37. -------------------------
  38.  
  39.   Below is the structure of a typical program using the interface:
  40.  
  41. - Program header:
  42. - Declaration of global variables and interface "objects".
  43. - Normal subroutines.
  44. - Subroutines called from the interface objects ("callbacks").
  45. - Main program:
  46. - Normal initialization.
  47. - Interface initialization: call to "xv_init".
  48. - Creation and initialization of the interface objects: calls to
  49.   "xv_create" followed by direct initialization of the object parameters.
  50. - Passing of control to the interface "notifier": call to "xv_main_loop".
  51. - Normal termination.
  52.  
  53. INTERFACE OBJECTS
  54. -----------------
  55.  
  56.   The user interface is composed of "objects". Note that the interface was
  57. not programmed with "object-oriented" specific techniques, but some ideas
  58. are used.
  59.   There are eight types of predefined objects, listed below. Their names
  60. are the parameters to be passed to the "xv_create" procedure.
  61.  
  62. - "frame":     Base windows, where the other objects are.
  63. - "button":    Command buttons.
  64. - "textfield": Input fields for text and numerical values, with edition.
  65. - "setting":   Input fields for logical values (choices).
  66. - "message":   Messages or icons in the windows.
  67. - "canvas":    Graphical output subwindows.
  68. - "tty":       Text output subwindows.
  69. - "menu":      Pop-up menus.
  70.  
  71.   Other types of objects can be programmed, if necessary, by adding the
  72. desired functionality to "canvas" objects through their "callback"
  73. routines. See the example program ROTOR.PAS.
  74.  
  75. EVENT-ORIENTED PROGRAMMING
  76. --------------------------
  77.  
  78.   The interface is intended to be used in an event-oriented program. The
  79. basic ideas are:
  80.  
  81.   The program does not follow a predefined fluxogram, but is commanded by
  82. the user, that generates "events" by acting on the objects in the windows,
  83. what causes calls to the "callback" routines, where the program functional
  84. code is located.
  85.   Any "callback" subroutine can be called at any moment. In its initial
  86. code, it can be necessary for the routine to check the program status to
  87. determine what is to be done. The program status can be maintained in a set
  88. of global logical variables, and/or in the "textfield", "setting", and
  89. "menu" objects.
  90.   The "callback" routines have complete control of the machine while active.
  91. They can open or close windows using "open_window" and "close_window",
  92. draw in "canvas" objects using the normal graphical functions, print
  93. messages in "tty" (using "ttysw_output") or "message" objects (using
  94. "xv_set"), or anything else that does not corrupt the interface structures.
  95.   The user is never prompted for information in a way that blocks the
  96. program execution (it is possible, if necessary, through windows with
  97. exclusive access (see the file EXCLUSIV.INC), but not recommended). The
  98. procedure for getting information from the user is to open a window with
  99. items to filled. "Callback" routines associated with the window objects
  100. update the program status and continue the execution, when and if the user
  101. commands.
  102.   The program never reads the keyboard or mouse directly (it is possible,
  103. using the normal functions and the MICKEY module functions, but also not
  104. recommended). All the inputs from the user are received as events and actions
  105. on the objects.
  106.  
  107.   The objects call "callback" routines by three mechanisms, associated with
  108. the object attributes:
  109.  
  110. "notify_handler": A "callback" routine, called when:
  111. - "frame": The window is closed.
  112. - "texfield": The return key is pressed, at the end of an edition.
  113. - "canvas": The window is redrawn, on the opening and resizing of the
  114.   window.
  115. - Other objects: The left mouse button is pressed over the object.
  116.  
  117. "event_handler": A "callback" routine, called when the state of the mouse
  118. changes over the object, or when a key is pressed, with the mouse pointer
  119. over the object.
  120.  
  121. "menu_name": Name of a "menu", opened with the right mouse button pressed
  122. over the object. The menus normally have an associated "notify handler",
  123. called when a selection is done. It is also possible to open a menu
  124. programatically, using the "menu_show" procedure. The items of a menu can
  125. have an associated "item_submenu" (name of another menu),also opened with
  126. the right mouse button. The same is valid for submenus of any order. The
  127. left mouse button always cause the selection of the present item, even if
  128. there are submenus. The central mouse button (or both right and left
  129. buttons simultaneously) cause the dismiss of menus without a call to the
  130. menu "notify_handler".
  131.  
  132.   The "callback" routines have always the same structure. They are far
  133. procedures receiving a single argument, that is the calling object pointer.
  134. Using this pointer, the parameters of the calling object can be accessed.
  135.  
  136. EVENTS
  137. ------
  138.  
  139.   The "event_handler" routines can read the event that caused the call in
  140. the global variable "ie_code". Its meanings are:
  141.  
  142. - Mouse events: "ie_code" contains:
  143.   LOC_MOVE: Movement.
  144.   LOC_DRAG: Movement with some button pressed.
  145.   MS_LEFT: Left button pressed.
  146.   MS_MIDDLE: Central button pressed.
  147.   MS_RIGHT: Right button pressed.
  148.   The state of the mouse buttons (as returned by the DOS interrupt 33) is in
  149. the global variable "ie_shiftcode".
  150.   The event names above are predefined constants. In the general case for
  151. button events, "ie_code"=1000+10*<buttons before>+<buttons after>.
  152.   The mouse position, relative to the object upper left corner, is in the
  153. global variables "ie_locx" and "ie_locy". The absolute mouse position is also
  154. available in the variables "mousex" and "mousey", defined in the MICKEY
  155. module.
  156.  
  157. - Keyboard events: "ie_code" contains the ASCII code of the pressed key. In
  158. the case of keys with extended codes, "ie_code" contains 2000+2nd code.
  159. With the mouse emulator in operation (see the MOUSE DRIVER section), events
  160. that are used by the emulator are not generated, unless the ScrollLock key is
  161. active, what returns the keyboard to normal operation.
  162.  
  163.   Some events interpreted by the interface are not passed to the
  164. "event_handlers". Only the "canvas" objects receive all the events. In any
  165. way, there is no much sense in detecting events over other objects.
  166.  
  167. WINDOWS
  168. -------
  169.  
  170.   There is always an active window, which "f